Skip Headers

Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# OCI String Functions

This section describes the OCI string functions.

Table 18-17 String Functions

Function/Page | Purpose
--- | ---
OCIStringAllocSize() | Get allocated size of string memory in bytes
OCIStringAssign() | Assign string to string
OCIStringAssignText() | Assign text string to string
OCIStringPtr() | Get string pointer
OCIStringResize() | Resize string memory
OCIStringSize() | Get string size

## OCIStringAllocSize()

Purpose

Gets allocated size of string memory in codepoints (Unicode) or in bytes.

Syntax

    sword OCIStringAllocSize ( OCIEnv              *env,
                               OCIError            *err,
                               CONST OCIString     *vs,
                               ub4                 *allocsize );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

vs (IN)

  String whose allocated size in bytes is returned. `vs` must be a non-`NULL` pointer.

allocsize (OUT)

  The allocated size of string memory in bytes is returned.

Comments

The allocated size is greater than or equal to the actual string size.

Related Functions

OCIErrorGet(), OCIStringResize(), OCIStringSize()

## OCIStringAssign()

Purpose

Assigns one string to another string.

Syntax

    sword OCIStringAssign ( OCIEnv               *env,
                            OCIError             *err,
                            CONST OCIString      *rhs,
                            OCIString            **lhs );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

rhs (IN)

  Right-hand side (source) of the assignment. Can be in UTF-16.

lhs (IN/OUT)

  Left-hand side (target) of the assignment. Its buffer is UTF-16 if `rhs` is UTF-16.

Comments

Assigns `rhs` string to `lhs` string. The `lhs` string may be resized depending upon the size of the `rhs`. The assigned string is `NULL`-terminated. The length field will not include the extra codepoint or byte needed for `NULL`-termination.

This function returns an error if the assignment operation runs out of space.

Related Functions

OCIErrorGet(), OCIStringAssignText()

## OCIStringAssignText()

Purpose

Assigns the source text string to the target string.

Syntax

    sword OCIStringAssignText ( OCIEnv           *env,
                                OCIError         *err,
                                CONST OraText    *rhs,
                                ub2              rhs_len,
                                OCIString        **lhs );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

rhs (IN)

  Right-hand side (source) of the assignment, a text or UTF-16 Unicode string.

rhs_len (IN)

  Length of the `rhs` string in bytes.

lhs (IN/OUT)

  Left-hand side (target) of the assignment. Its buffer is Unicode if `rhs` is Unicode.

Comments

Assigns `rhs` string to `lhs` string. The `lhs` string may be resized depending upon the size of the `rhs`. The assigned string is `NULL`-terminated. The length field will not include the extra byte or codepoint needed for `NULL`-termination.

Related Functions

OCIErrorGet(), OCIStringAssign()

## OCIStringPtr()

Purpose

Gets a pointer to the text of a given string.

Syntax

    text *OCIStringPtr ( OCIEnv               *env,
                         CONST OCIString      *vs );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

vs (IN)

  Pointer to the `OCIString` object whose character string will be returned. If `vs` is in UTF-16, the returned buffer will also be UTF-16. If you want to know the encoding of the returned buffer, check the UTF-16 information in the `OCIString` `vs` itself, since it is not guaranteed that a particular `OCIString` must have the same setting as `env` does. The function to check should be some object OCI function designed to check member fields in objects.

Comments

None.

Related Functions

OCIErrorGet(), OCIStringAssign()

## OCIStringResize()

Purpose

Resizes the memory of a given string.

Syntax

    sword OCIStringResize ( OCIEnv          *env,
                            OCIError        *err,
                            ub4             new_size,
                            OCIString       **str );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

new_size (IN)

  New memory size of the string in bytes. `new_size` must include space for the `NULL` character as the string terminator.

str (IN/OUT)

  Allocated memory for the string which is freed from the OCI object cache.

Comments

This function resizes the memory of the given variable-length string in the object cache. Contents of the string are not preserved. This function may allocate the string in a new memory region, in which case the original memory occupied by the given string is freed. If `str` is `NULL`, this function allocates memory for the string. If `new_size` is 0, this function frees the memory occupied by `str` and a `NULL` pointer value is returned.

Related Functions

OCIErrorGet(), OCIStringAllocSize(), OCIStringSize()

## OCIStringSize()

Purpose

Gets the size of the given string `vs`.

Syntax

    ub4 OCIStringSize ( OCIEnv              *env,
                        CONST OCIString     *vs );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

vs (IN)

  String whose size is returned, in number of bytes.

Comments

The returned size does not include an extra byte for `NULL` termination.

Related Functions

OCIErrorGet(), OCIStringResize()